---
title: Install Weave GitOps Enterprise
hide_title: true
pagination_next: enterprise/getting-started/releases-enterprise
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import TierLabel from "../../_components/TierLabel";
import CurlCodeBlock from "../../_components/CurlCodeBlock";
import oauthBitbucket from '/img/oauth-bitbucket.png';
import oauthAzureDevOps from '/img/oauth-azure-devops.png';
import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png';

## Install Weave GitOps Enterprise<TierLabel tiers="Enterprise" />

:::info
To purchase an entitlement to Weave GitOps Enterprise, please contact [info@weaveworks.org](mailto:info@weaveworks.org).
:::

Follow the instructions on this page to:

import TOCInline from "@theme/TOCInline";

<TOCInline toc={(() => {
           const trimStart = toc.slice(toc.findIndex((node) => node.id == 'install-weave-gitops-enterprise')+1);
           return trimStart.slice(0, trimStart.findIndex((node) => node.level == '2'));
           })()} />

:::tip
There is no need to install the open source version of Weave GitOps before installing Weave GitOps Enterprise.
:::

### Prep Step: Create a Repository
Create a new private GitHub repository and give it a name. We'll call our repo `fleet-infra`.

Set up a Git client for your private repo. For GitHub, see their docs on [setting your username](https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git#setting-your-git-username-for-every-repository-on-your-computer) and [setting your email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-email-address-for-every-repository-on-your-computer).

### 1. Set up a Management Cluster with `flux`

These steps reflect [Flux](https://fluxcd.io/flux/)’s architecture and operations. 

To get you started, we'll cover:

- `kind` as our management cluster with the _CAPD_ provider
- **EKS** as our management cluster with the _CAPA_ provider

Note that Weave GitOps Enterprise supports any combination of management cluster and CAPI provider.

<Tabs groupId="infrastructure" default>
<TabItem value="kind" label="kind">

##### 1.1 We start by creating a kind-config

```yaml title="kind-config.yaml"
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraMounts:
      - hostPath: /var/run/docker.sock
        containerPath: /var/run/docker.sock
```

The `extraMounts` enable the Docker CAPI provider (CAPD) to talk to the host docker.

##### 1.2 Start your kind cluster using the configuration above and Kubernetes v1.23.6

```bash
kind create cluster --config kind-config.yaml --image=kindest/node:v1.23.6
```

</TabItem>
<TabItem value="eks" label="EKS">

##### 1.1 Prepare IAM for installation

Cluster API needs special permissions in AWS. Use the `clusterawsadm` command below to roll out a CloudStack and install the permissions into your AWS account. Although the CloudStack is bound to a region, the resulting permissions are globally scoped. You can use any AWS Region that you have access to. 

The `clusterawsadm` command takes an AWSIAMConfiguration file. We have provided a working example for you:

```yaml title="eks-config.yaml"
apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
kind: AWSIAMConfiguration
spec:
  bootstrapUser:
    enable: true
  eks:
    iamRoleCreation: false # Set to true if you plan to use the EKSEnableIAM feature flag to enable automatic creation of IAM roles
    defaultControlPlaneRole:
      disable: false # Set to false to enable creation of the default control plane role
    managedMachinePool:
      disable: false # Set to false to enable creation of the default node pool role
```

Run the `clusterawsadm` command to create the IAM group.

```bash
$ clusterawsadm bootstrap iam create-cloudformation-stack --config eks-config.yaml --region $REGION
```

Create an IAM User. This user will be used as a kind of service account. Assign the newly created group to this user. The group name will be something like: `cluster-api-provider-aws-s-AWSIAMGroupBootstrapper-XXXX`. Create a secret for the newly created IAM user.

##### 1.2 Create the cluster

In testing, we used the following values:
`$INSTANCESIZE` : t3.large
`$NUMOFNODES` : 2
`$MINNODES` : 2
`$MAXNODES` : 6

```bash
eksctl create cluster -n "$CLUSTERNAME" -r "$REGION" --nodegroup-name workers -t $INSTANCESIZE --nodes $NUMOFNODES --nodes-min $MINNODES --nodes-max $MAXNODES --ssh-access --alb-ingress-access
```

##### 1.3 Add cluster to kubeconfig

Once the cluster is created, add the cluster to your `kubeconfig`:

```bash
aws eks --region "$REGION" update-kubeconfig --name "$CLUSTERNAME"
```

</TabItem>
</Tabs>

##### Install Flux onto your cluster with the `flux bootstrap` command

<Tabs groupId="infrastructure" default>
<TabItem value="github" label="GITHUB">

```bash
flux bootstrap github \
  --owner=<github username> \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/management \
  --personal
  --components-extra image-reflector-controller,image-automation-controller
```

</TabItem>

<TabItem value="gitlab" label="GITLAB">

```bash
flux bootstrap gitlab \
  --owner=<gitlab username> \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/management \
  --personal
```

</TabItem>


</Tabs>

Your private GitHub repo should have a clusters/management folder that includes the manifests Flux needs to operate, and that also generates a key value pair for Flux to access the repo.

* **owner**      - The username (or organization) of the git repository
* **repository** - Git repository name
* **branch**     - Git branch (default "main")
* **path**       - Path relative to the repository root; when specified, the cluster sync will be scoped to this path
* **personal**   - If set, the owner is assumed to be a repo user

Go [here](https://fluxcd.io/docs/cmd/) for more information about `flux` and the `flux bootstrap` command. 

:::note At this point your Flux management cluster should be running. Take a look at the repository you created earlier.
:::

### 2. Install a CAPI provider

:::note `clusterctl` versions

Download a specific version of clusterctl from the [releases page](https://github.com/kubernetes-sigs/cluster-api/releases). We've tested the example templates provided in this guide with `clusterctl` version `1.1.3`. You might need to use a different version, depending on the CAPI provider you plan to use.

:::

You must install a CAPI provider to provision Kubernetes clusters. Visit the [Cluster API Providers](../../cluster-management/cluster-api-providers.mdx) page for more details on providers.

Here we'll continue with our example instructions for CAPD and CAPA.

<Tabs groupId="infrastructure" default>
<TabItem value="kind" label="CAPD (kind)">

```bash
# Enable support for `ClusterResourceSet`s for automatically installing CNIs
export EXP_CLUSTER_RESOURCE_SET=true

clusterctl init --infrastructure docker
```

</TabItem>
<TabItem value="eks" label="CAPA (EKS)">

```bash
export EXP_EKS=true
export EXP_MACHINE_POOL=true
export CAPA_EKS_IAM=true
export EXP_CLUSTER_RESOURCE_SET=true

clusterctl init --infrastructure aws
```

</TabItem>
</Tabs>

### 3. Apply the entitlements secret

Contact info@weaveworks.org for a valid entitlements secret. Then apply it to the cluster:

```bash
kubectl apply -f entitlements.yaml
```

### 4. Configure access for writing to git from the UI

<Tabs groupId="git-provider" default>
<TabItem value="github" label="GitHub">
GitHub requires no additional configuration for OAuth git access
</TabItem>
<TabItem value="gitlab" label="GitLab">

Create a GitLab OAuth application that will request `api` permissions to create pull requests on the user's behalf.

Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html).

The application should have at least these scopes:

- `api`
- `openid`
- `email`
- `profile`

Add callback URLs to the application for each address the UI will be exposed on, e.g.:

- `https://localhost:8000/oauth/gitlab` For port-forwarding and testing
- `https://git.example.com/oauth/gitlab` For production use

Save your application and take note of the **Client ID** and **Client Secret**. Save
them into the `git-provider-credentials` secret, along with:

- `GIT_HOST_TYPES` to tell WGE that the host is gitlab
- `GITLAB_HOSTNAME` where the OAuth app is hosted

**Replace values** in this snippet and run:

```bash
kubectl create secret generic git-provider-credentials --namespace=flux-system \
  --from-literal="GITLAB_CLIENT_ID=13457" \
  --from-literal="GITLAB_CLIENT_SECRET=24680" \
  --from-literal="GITLAB_HOSTNAME=git.example.com" \
  --from-literal="GIT_HOST_TYPES=git.example.com=gitlab"
```

</TabItem>
<TabItem value="bitbucket-server" label="BitBucket Server">

Create a new [incoming application link](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html) from
the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL
should be set to `<WGE dashboard URL>/oauth/bitbucketserver`. You will also need to select permissions for the application. The minimum set of
permissions needed for WGE to create pull requests on behalf of users is `Repositories - Write`. An example of configuring these settings is shown below.

<figure>

<img src={oauthBitbucket} width="500"/>

<figcaption>Configuring a new incoming application link</figcaption>
</figure>


Save your application and take note of the **Client ID** and **Client Secret**. Save
them into the `git-provider-credentials` secret, along with:

- `GIT_HOST_TYPES` to tell WGE that the host is bitbucket-server
- `BITBUCKET_SERVER_HOSTNAME` where the OAuth app is hosted

**Replace values** in this snippet and run:

```bash
kubectl create secret generic git-provider-credentials --namespace=flux-system \
  --from-literal="BITBUCKET_SERVER_CLIENT_ID=13457" \
  --from-literal="BITBUCKET_SERVER_CLIENT_SECRET=24680" \
  --from-literal="BITBUCKET_SERVER_HOSTNAME=git.example.com" \
  --from-literal="GIT_HOST_TYPES=git.example.com=bitbucket-server"
```

If the secret is already present, use the following command to update it using your default editor:

```bash
kubectl edit secret generic git-provider-credentials --namespace=flux-system
```

:::info

If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: `GIT_HOST_TYPES=git.example.com:7990=bitbucket-server`

:::

</TabItem>
<TabItem value="azure-devops" label="Azure DevOps">

Navigate to https://app.vsaex.visualstudio.com/app/register and register a new application, as explained in the [docs](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops#1-register-your-app). Set the authorization callback URL and select which scopes to grant. Set the callback URL to `<WGE dashboard URL>/oauth/azuredevops`. 

Select the `Code (read and write)` scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below.

<figure>
<img src={oauthAzureDevOps}/>
<figcaption>Creating a new application</figcaption>
</figure>

After creating your application, you will be presented with the application settings. Take note of the `App ID` and `Client Secret` values—you will use them to configure WGE.

<figure>
<img src={oauthAzureDevOpsSuccess}/>
<figcaption>Application settings</figcaption>
</figure>

In your cluster, create a secret named `git-provider-credentials` that contains the `App ID` and `Client Secret` values from the newly created application.

**Replace values** in this snippet and run:

```bash
kubectl create secret generic git-provider-credentials --namespace=flux-system \
  --from-literal="AZURE_DEVOPS_CLIENT_ID=<App ID value>" \
  --from-literal="AZURE_DEVOPS_CLIENT_SECRET=<Client Secret value>"
```

WGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me.

</TabItem>
</Tabs>


### 5. Configure and Commit

We deploy WGE via a Helm chart. We'll save and adapt the below template before committing it in Git to a Flux-reconciled path.

Clone the newly created repo locally. We're gonna add some things!

```
git clone git@<provider>:<username>/fleet-infra
cd fleet-infra
```

Download the helm-release to `clusters/management/weave-gitops-enterprise.yaml`.

import ExampleWGE from "../../assets/example-enterprise-helm.yaml";
import ExampleWGEContent from "!!raw-loader!../../assets/example-enterprise-helm.yaml";

<details>
<summary>Expand to see file contents</summary>

<CurlCodeBlock
  localPath="clusters/management/weave-gitops-enterprise.yaml"
  hostedPath={ExampleWGE}
  content={ExampleWGEContent}
/>

</details>

Once you have copied the above file, open and adjust the following configuration
options:

#### `values.config.capi.repositoryURL`
Ensure this has been set to your repository URL.

#### `values.config.capi.repositoryPath`
By default, WGE will create new clusters in the `clusters/management/clusters` path.
You can configure it with `values.config.capi.repositoryPath`.
You might what to change it to `clusters/my-cluster/cluster` if you configured Flux to reconcile `./clusters/my-cluster` instead.

#### `values.config.capi.repositoryClustersPath`
The other important path to configure is where you'll store applications and workloads run on the new cluster.
By default this is `./clusters`. When a new cluster is specified, any selected profiles will be written to `./clusters/{.namespace}/{.clusterName}/profiles.yaml`.
When the new cluster is bootstrapped, Flux will sync the `./clusters/{.namespace}/{.clusterName}` path.

#### (Optional) Install policy agent

[Policy agent](../../policy/intro.mdx) comes packaged with the WGE chart. To install it, set the following values:

- `values.policy-agent.enabled`: set to true to install the agent with WGE
- `values.policy-agent.config.accountId`: organization name, used as identifier
- `values.policy-agent.config.clusterId`: unique identifier for the cluster

Commit and push all the files

```bash
git add clusters/management/weave-gitops-enterprise.yaml
git commit -m "Deploy Weave GitOps Enterprise"
git push
```

Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the `flux-system` namespace to verify all pods are running.

### 6. Configure password

To login to the WGE UI, generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster.

There are several different ways to generate a bcrypt hash. This guide uses `gitops get bcrypt-hash` from our CLI, which you can install with [these instructions](#7-install-the-cli).

```bash
PASSWORD="<Make up and insert a brand-new password here. Keeping the quotes, but remove the brackets.>"
echo -n $PASSWORD | gitops get bcrypt-hash
$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q
```

Use the hashed output to create a Kubernetes username/password secret. Insert it in the last line of this command, replacing what’s currently shown within the quotation marks ('$2a$.......').


```bash
kubectl create secret generic cluster-user-auth \
  --namespace flux-system \
  --from-literal=username=wego-admin \
  --from-literal=password='$2a$.......'
```

### 7. Install the CLI
Install the Weave GitOps Enterprise CLI tool.
You can use brew or curl.

```console
brew install weaveworks/tap/gitops-ee
```

```bash
curl --silent --location "https://artifacts.wge.dev.weave.works/releases/bin/0.22.0/gitops-$(uname | tr '[:upper:]' '[:lower:]')-$(uname -m).tar.gz" | tar xz -C /tmp
sudo mv /tmp/gitops /usr/local/bin
gitops version
```

## Next steps

Check out:

- [Cluster Management - Getting started](../../cluster-management/getting-started.mdx) to create your first CAPI Cluster with `kind`/CAPD.
- [Deploying CAPA with EKS](../../guides/deploying-capa.mdx) to create your first CAPI Cluster with EKS/CAPA.

### (Optional) Install the Terraform Controller

The [Terraform Controller](https://weaveworks.github.io/tf-controller/) is a controller for Flux to reconcile Terraform resources in a GitOps way.

With Flux and the TF-Controller, WGE makes it easy to add Terraform templates to clusters and continuously reconcile any changes made to the Terraform source manifest.

Check out our guide on [how to use Terraform templates](../../guides/using-terraform-templates.mdx). Then try your hands at using it with the RDS example!

Install the TF-Controller to a cluster using Helm:

```console
# Add tf-controller helm repository
helm repo add tf-controller https://weaveworks.github.io/tf-controller/

# Install tf-controller
helm upgrade -i tf-controller tf-controller/tf-controller \
    --namespace flux-system
```

Consult the TF-Controller [Installation documentation](https://weaveworks.github.io/tf-controller/getting_started/) for more details on which parameters are configurable and how to install a specific version.
